NAME¶

libpfm - a helper library to program Hardware Performance Units (PMUs)

SYNOPSIS¶

#include <perfmon/pfmlib.h>

DESCRIPTION¶

The libpfm library is a helper library which is used by applications to help program the Performance Monitoring Unit (PMU), i.e., the hardware performance counters of modern processors. It provides a generic and portable programming interface to help setup the PMU configuration registers given a list of events to measure.

A diversity of PMU hardware is supported, a list can be found below under SUPPORTED HARDWARE. The library is primarily designed to be used in conjunction with the Perfmon2 Linux kernel interface. However, at its core, it is totally independent of that interface and could as well be used on other operating systems. It is important to realize that the library does not make the actual kernel calls to program the PMU, it simply helps applications figure out which PMU registers to use to measure certain events or access certain advanced PMU features.

The library logically divides PMU registers into two categories. The performance monitoring data registers (PMD) are used to collect results, e.g., counts. The performance monitoring configuration registers (PMCS) are used to indicate what events to measure or what feature to enable. Programming the PMU consists in setting up the PMC registers and collecting the results in the PMD registers. The central piece of the library is the pfm_dispatch_events function.

The number of PMC and PMD registers varies between architectures and CPU models. The association of PMC to PMD can also change. Moreover the number and encodings of events can also widely change. Finally, the structure of a PMC register can also change. All these factors make it quite difficult to write monitoring tools.

This library is designed to simplify the programming of the PMC registers by hiding the complexity behind a simple interface. The library does this without limiting accessibility to model specific features by using a layered design.

The library is structured in two layers. The common layer provides an interface that is shared across all PMU models. This layer is good enough to setup simple monitoring sessions which count occurrences of events. Then, there is a model-specific layer which gives access to the model-specific features. For instance, on Itanium, applications can use the library to setup the registers for the Branch Trace Buffer. Model-specific interfaces have the abbreviated PMU model name in their names. For instance, pfm_ita2_get_event_umask() is an Itanium2 (ita2) specific function.

When the library is initialized, it automatically probes the host CPU and enables the right set of interfaces.

The common interface is defined in the pfmlib.h header file. Model-specific interfaces are defined in model-specific header files. For instance, pfmlib_amd64.h provides the AMD64 interface.

ENVIRONMENT VARIABLES¶

It is possible to enable certain debug output of the library using environment variables. The following variables are defined:

LIBPFM_VERBOSE

Enable verbose output. Value must be 0 or 1. When not set, verbosity level can be controlled with this function.

LIBPFM_DEBUG

Enable debug output. Value must be 0 or 1. When not set, debug level can be controlled with this function.

LIBPFM_DEBUG_STDOUT

Redirect verbose and debug output to the standard output file descriptor (stdout). By default, the output is directed to the standard error file descriptor (stderr).

Alternatively, it is possible to control verbosity and debug output using the pfm_set_options function.

SUPPORTED HARDWARE¶

libpfm_amd64(3)     AMD64 processors K8 and Barcelona (families 0Fh and 10h)
libpfm_core(3)      Intel Core processor family
libpfm_atom(3)      Intel Atom processor family
libpfm_itanium(3)   Intel Itanium
libpfm_itanium2(3)  Intel Itanium 2
libpfm_montecito(3) Intel dual-core Itanium 2 9000 (Montecito)
libpfm_p6(3)        P6 processor family including the Pentium M processor
libpfm_powerpc(3)   IBM PowerPC and POWER processor families


                    (PPC970(FX,GX), PPC970MP POWER4, POWER4+, POWER5,


                    POWER5+, and POWER6)

AUTHORS¶

Stephane Eranian <eranian@hpl.hp.com>
Robert Richter <robert.richter@amd.com>

SEE ALSO¶

libpfm(3), libpfm_amd64(3), libpfm_core(3), libpfm_itanium2(3), libpfm_itanium(3), libpfm_montecito(3), libpfm_p6(3), libpfm_powerpc(3).

pfm_dispatch_events(3), pfm_find_event(3), pfm_set_options(3),
pfm_get_cycle_event(3), pfm_get_event_name(3), pfm_get_impl_pmcs(3),
pfm_get_pmu_name(3), pfm_get_version(3), pfm_initialize(3),
pfm_regmask_set(3), pfm_set_options(3), pfm_strerror(3).

Examples shipped with the library